home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / fam.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-04-25  |  11.3 KB  |  315 lines
  1. /*
  2.     Copyright (C) 1999-2003 Silicon Graphics, Inc.  All Rights Reserved.
  3.  
  4.     This program is free software; you can redistribute it and/or modify it
  5.     under the terms of version 2.1 of the GNU Lesser General Public License
  6.     as published by the Free Software Foundation.
  7.  
  8.     This program is distributed in the hope that it would be useful, but
  9.     WITHOUT ANY WARRANTY; without even the implied warranty of
  10.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  Further, any
  11.     license provided herein, whether implied or otherwise, is limited to
  12.     this program in accordance with the express provisions of the GNU Lesser
  13.     General Public License.  Patent licenses, if any, provided herein do not
  14.     apply to combinations of this program with other product or programs, or
  15.     any other product whatsoever. This program is distributed without any
  16.     warranty that the program is delivered free of the rightful claim of any
  17.     third person by way of infringement or the like.  See the GNU Lesser
  18.     General Public License for more details.
  19.  
  20.     You should have received a copy of the GNU General Public License along
  21.     with this program; if not, write the Free Software Foundation, Inc., 59
  22.     Temple Place - Suite 330, Boston MA 02111-1307, USA.
  23. */
  24.  
  25. #ifndef _FAM_
  26. #define _FAM_
  27. #ifdef __cplusplus
  28. extern "C" {
  29. #endif
  30.  
  31.  
  32. /*****************************************************************************
  33. *
  34. *  MODULE:  Fam.h - File Alteration Monitor 
  35. *
  36. *   Fam allows applications to monitor files - receiving events when they
  37. *   change.  The scheme is simple:  Applications register which
  38. *   files/directories they are interested, and fam will notify the
  39. *   application when any of these files are changed.
  40. *
  41. *****************************************************************************/
  42.  
  43. /* For NAME_MAX - maximum # of chars in a filename */
  44. #include <limits.h>
  45.  
  46.  
  47.  
  48.  
  49.  
  50. /*****************************************************************************
  51. *  DATA STRUCTURES
  52. *
  53. *
  54. *  FAMConnection Structure:
  55. *
  56. *  The FAMConnection Data structure is created when opening a connection
  57. *  to fam.  After that, it is passed into all fam procedures.  This
  58. *  structure has all the information in it to talk to fam (Currently,
  59. *  the only data inside this structure is a file descriptor for
  60. *  the socket to fam).  
  61. *****************************************************************************/
  62.  
  63. typedef struct FAMConnection {
  64.     int fd;
  65.     void *client;
  66. } FAMConnection;
  67.  
  68.  
  69. /*****************************************************************************
  70. *  To access the fd inside this structure (so the application writer can
  71. *  use select for fam events), the following macro is defined (this will 
  72. *  allow us to change the implementation without users having to change 
  73. *  their code):
  74. *****************************************************************************/
  75. #define FAMCONNECTION_GETFD(fc)      ((fc)->fd)
  76.  
  77.  
  78.  
  79.  
  80.  
  81. /*****************************************************************************
  82. *  FAMRequest Structure:
  83. *
  84. *  Every time fam is called on to monitor a file, it passes back a
  85. *  FAMRequest structure.  The main piece of data that this structure 
  86. *  contans is a reqnum.  This reqnum is guaranteed to be unique.  When
  87. *  cancelling or suspending a monitor request, you must pass this
  88. *  data structure into FAMCancelMonitor or FAMSuspendMonitor to
  89. *  make sure that you are cancelling/suspending the correct request
  90. *  (You can monitor the same file/directory more than once).
  91. *****************************************************************************/
  92.  
  93. typedef struct FAMRequest {
  94.     int reqnum;
  95. } FAMRequest;
  96.  
  97.  
  98. /*****************************************************************************
  99. *  Once again, to access the reqnum inside this structure, use the
  100. *  following macro:
  101. *****************************************************************************/
  102. #define FAMREQUEST_GETREQNUM(fc)     ((fc)->reqnum)
  103.  
  104.  
  105.  
  106. /*****************************************************************************
  107. *  FAMEvent Structure:
  108. *
  109. *  When a file/directory has been modified/deleted, fam will pass
  110. *  a FAMEvent structure to the application (through the callback
  111. *  in the FAMMonitorFile/Directory routines).  This structure will
  112. *  describe what event happened to the file.  The different events
  113. *  that can happen to a file are listed in the FAMCodes enum.
  114. *****************************************************************************/
  115. enum FAMCodes { FAMChanged=1, FAMDeleted=2, FAMStartExecuting=3, 
  116.         FAMStopExecuting=4, FAMCreated=5, FAMMoved=6, 
  117.         FAMAcknowledge=7, FAMExists=8, FAMEndExist=9 };
  118.  
  119. typedef struct  FAMEvent {
  120.     FAMConnection* fc;         /* The fam connection that event occurred on */
  121.     FAMRequest fr;             /* Corresponds to the FamRequest from monitor */
  122.     char *hostname;            /* host and filename - pointer to which */
  123.     char filename[PATH_MAX];   /* file changed */
  124.     void *userdata;            /* userdata associated with this monitor req. */
  125.     enum FAMCodes code;        /* What happened to file - see above */
  126. } FAMEvent;
  127.  
  128.  
  129.  
  130.  
  131.  
  132. /*****************************************************************************
  133. *  ERROR HANDLING
  134. *
  135. *  If an error occurs inside of libfam, a global named FAMErrno is set
  136. *  to a non-zero value and the routine that the error occurred in will 
  137. *  return an error value (usually NULL).  FAMErrlist is a global
  138. *  string array (indexed by FAMErrno) that describes the last error 
  139. *  that happened;
  140. *
  141. *  NOTE: currently FAMErrno and FamErrList are unused
  142. *****************************************************************************/
  143.  
  144. extern int FAMErrno;
  145. extern char *FamErrlist[];
  146.  
  147. /*
  148. *[NOTE: Eventually, there will be a bunch of defines right here defining what
  149. * errors can happen in using libfam ]
  150. */
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157. /*****************************************************************************
  158. *  PROCEDURES:
  159. *
  160. *  FAMOpen, FAMClose
  161. *
  162. *  The first step that an application has to do is open a connection to
  163. *  fam.  This is done through the FAMOpen.  FAMOpen returns a FAMConnection
  164. *  data structure which is passed to all fam procedures.  FAMClose closes
  165. *  a fam connection.  
  166. *
  167. *  On error, FAMOpen will return NULL and FAMClose will return -1 (and
  168. *  FAMErrno will be set to the value of the error).  
  169. *****************************************************************************/
  170.  
  171. extern int FAMOpen(FAMConnection* fc);
  172. extern int FAMOpen2(FAMConnection* fc, const char* appName);
  173. extern int FAMClose(FAMConnection* fc);
  174.  
  175.  
  176.  
  177. /*****************************************************************************
  178. *  FAMMonitorDirectory, FAMMonitorFile
  179. *
  180. *  These routines tell fam to start monitoring a file/directory.  The
  181. *  parameters to this function are a FAMConnection (received from FAMOpen),
  182. *  a filename and a user data ptr.  A FAMRequest structure is returned.
  183. *  When the file/directory changes, a fam event structure will be 
  184. *  generated.  The application can retrieve this structure by calling
  185. *  FAMNextEvent (see description under FAMNextEvent).
  186. *
  187. *  The difference between these two routines is that FAMMonitorDirectory
  188. *  monitors any changes that happens to the contents of the directory
  189. *  (as well as the directory file itself) and FAMMonitorFile monitors
  190. *  only what happens to a particular file.
  191. *
  192. *  On error FAMMonitorDirectory/File will return NULL (and FAMErrno will
  193. *  be set to the value of the error).  
  194. *****************************************************************************/
  195.  
  196. extern int FAMMonitorDirectory(FAMConnection *fc,
  197.                    const char *filename,
  198.                    FAMRequest* fr,
  199.                    void* userData);
  200. extern int FAMMonitorFile(FAMConnection *fc,
  201.               const char *filename, 
  202.               FAMRequest* fr,
  203.               void* userData);
  204. extern int FAMMonitorCollection(FAMConnection *fc,
  205.                 const char *filename, 
  206.                 FAMRequest* fr,
  207.                 void* userData,
  208.                 int depth,
  209.                 const char* mask);
  210.  
  211. extern int FAMMonitorDirectory2(FAMConnection *fc,
  212.                 const char *filename,
  213.                 FAMRequest* fr);
  214. extern int FAMMonitorFile2(FAMConnection *fc,
  215.                const char *filename,
  216.                FAMRequest* fr);
  217.  
  218.  
  219. /*****************************************************************************
  220. *  FAMSuspendMonitor, FAMResumeMonitor
  221. *
  222. *  FAMSuspendMonitor enables applications to suspend
  223. *  receive events about files/directories that are changing.  This can
  224. *  be useful in situations when an application is stowed and does not
  225. *  want to receive events until it is unstowed.  FAMResumeMonitor
  226. *  signals fam to start monitoring the file/directory again.  
  227. *
  228. *  Both of these routines take a FAMConnection and a FAMRequest structure.
  229. *  The FAMRequest Structure is returned from the FAMMonitorFile/Directory
  230. *  routines.
  231. *
  232. *  On error, FAMResume/SuspendMonitor will return -1 (and the global
  233. *  FAMErrno will be set to the value of the error).
  234. *****************************************************************************/
  235.  
  236. int FAMSuspendMonitor(FAMConnection *fc, const FAMRequest *fr);
  237. int FAMResumeMonitor(FAMConnection *fc, const FAMRequest *fr);
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244. /*****************************************************************************
  245. *  FAMCancelMonitor
  246. *
  247. *  When an application is done monitoring a file/directory, it should
  248. *  call FAMCancelMonitor.  This routine will signal fam not to watch
  249. *  this directory anymore. Once again, the FAMRequest structure is
  250. *  returned from the FAMMonitorFile/Directory routines.
  251. *
  252. *  On error, FAMCancelMonitor will return -1 (and the global
  253. *  FAMErrno will be set to the value of the error).  This routine will free
  254. *  the FAMRequest structure that is passed in.
  255. *****************************************************************************/
  256.  
  257. int FAMCancelMonitor(FAMConnection *fc, const FAMRequest *fr);
  258.  
  259.  
  260.  
  261.  
  262. /*****************************************************************************
  263. *  FAMNextEvent, FAMPending
  264. *  
  265. *  FAMNextEvent will get the next fam event (file/directory change).  If 
  266. *  there are no fam events waiting, then FAMNextEvent will wait 
  267. *  until a fam event has been received (from fam).
  268. *
  269. *  FAMPending will return the number of fam events that are waiting.
  270. *  This routine always returns immediately to the caller.
  271. *
  272. *  Essentially, there are two ways to for applications to receive fam
  273. *  events:
  274. *
  275. *  1.  The "Polling" approach - Just call FAMPending periodically;
  276. *      like when the system is waiting for input.  If FAMPending returns
  277. *      with a positive return value, then there are fam events waiting.
  278. *      Call FAMNextEvent to receive the events.
  279. *
  280. *  2.  The "Select" approach - Use the fd returned from famOpen (in the
  281. *      FAMConnection structure) as one of the fds that the application
  282. *      selects on.  When select returns saying that data is on the fam
  283. *      fd, call FAMNextEvent.
  284. *
  285. *  FAMNextEvent reads any information that is on the fam socket,
  286. *  and returns it to the application (in the form of a FAMEvent).
  287. *
  288. *  On error, FAMNextEvent and FAMPendingEvent will return -1 (and the global
  289. *  FAMErrno will be set to the value of the error).
  290. *****************************************************************************/
  291.  
  292. int FAMNextEvent(FAMConnection *fc, FAMEvent *fe);
  293. int FAMPending(FAMConnection* fc);
  294.  
  295.  
  296.  
  297.  
  298. /*****************************************************************************
  299. *  FAMDebugLevel
  300. *  
  301. *  This doesn't do anything.
  302. *
  303. *****************************************************************************/
  304.  
  305. #define FAM_DEBUG_OFF 0
  306. #define FAM_DEBUG_ON  1
  307. #define FAM_DEBUG_VERBOSE 2
  308.  
  309. int FAMDebugLevel(FAMConnection *fc, int debugLevel);
  310.  
  311. #ifdef __cplusplus
  312. }
  313. #endif
  314. #endif  /* _FAM_ */
  315.